This greatly limits the usefulness of this information. To my knowledge, Javadoc, KDoc, Scaladoc and Pkl’s IntelliJ plugin all support cross-package information.

Pkldoc would still support cross-package information, but only "up" (who am I extending, what types am I using), just not "down" (who is using me).

As far as I know, neither Javadoc, KDoc, nor Scaladoc show information downwards.

IMO: I don't know how useful this information is, either. For commonly used enough types, this information becomes quite noisy.

Also: cross-package references like this are actually broken right now (they were intended to work, but they don't).
So, this actually isn't a regression.

As far as I know, neither Javadoc, KDoc, nor Scaladoc show information downwards.

From what I can see they all do, at least for subtypes.

Example (see “all known subinterfaces” etc.): https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/util/Collection.html

Ah, interesting! TIL.

But, this type of information is still only maintained some sort of local level. pkldoc is somewhat different, in that we can possibly generate docs of many, many packages. Imagine if the JDK's docs showed known subclasses of Collection for 3rd-party libs; that list would grow massively pretty quickly.

But, this type of information is still only maintained some sort of local level.

It’s as local or global as the user running Javadoc wants it to be. A Javadoc site can document any number of Java modules. It can also include information from any number of upstream Javadoc websites, which of course can’t depend on code documented by the current Javadoc site (only the other way around). I thought Pkldoc worked in the same way.

The JDK’s Javadoc documents dozens of modules, hundreds of packages, and thousands of classes. Even though every JDK version has its own Javadoc site, a single site is probably larger than Pkl Pantry’s multi-version Pkldoc.

Javadoc also tracks usages, but on a separate page: https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/util/class-use/Collection.html

If you’d like to reduce the amount of processing and information presented, one option is to track subtypes across packages and to drop usages altogether. This feels more useful to me than tracking some info across packages and other info only within a package.

Another option is to limit usage tracking to the package or package+module level.

pkldoc is somewhat different; in some cases, pkldoc sites serve as a central package documentation site (think https://pkg.go.dev/ or https://docs.rs). And in these cases, the site can be quite big; probably already several orders of magnitude larger than package_docs.

I see. “Arbitrarily” tracking some info only within packages is very surprising/limiting. If there’s no way around this, perhaps it should be reflected in the title, e.g., “subtypes within package”. Alternatively, this could be an option only used for central package doc sites.

Yeah, I suppose we can have a flag that determines whether known types/usages is tracked across packages or not. And if not, we can change the label to "Subtypes within package", etc.

By the way, this is actually broken today (cross-package known usage/subtype doesn't work).

Did you mean “intra-package”?

Yup, thanks!

Does this change turn these files into a public API? Is all contained information relevant/suitable for a public API? Have you considered having a separate public API?

pkldoc itself doesn't really care whether these should be a public API or not.
I guess whether these URLs end up being a "public API" depends on who is running the web server.

For our own package docs site, I don't think we would support this being used as an API.

BTW: one alternative that I thought about for managing metadata is to use a database (e.g. provide a jdbc connection string when running pkldoc). However, this is a much more involved change that would be quite a big rewrite of pkldoc. I can add some notes about this in the "alternatives considered".

We're also considering having a package index at some point, which would enable use-cases like: "bump my package to the latest version". This is orthogonal to pkldoc, though.

I don’t (only) mean if these files are served but if a (local) consumer can rely on their presence and format (since you mentioned “improve machine readability”). I’m asking
because I’m not sure if pkldoc’s internal metadata format should double as a public format with strict compatibility guarantees etc.

Gotcha.

No; these files are only meant for pkldoc itself to consume. It's not meant to be an API for any other use-cases, and it's possible that a future migration will change the current JSON files in a breaking way.